PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / sthing.com / STHING.DOC < prev next >

Wrap

Text File | 1990-10-28 | 24.0 KB | 597 lines

Turbo Pascal Access to the Covox Speech Thing Kim Kokkonen TurboPower Software October 1990 The Covox Speech Thing is a high-quality, cost effective system for adding speech capabilities to PC programs. For only about $80, you get an interface plug that connects to a PC's parallel port, an auxiliary speaker that connects to the interface plug, and the SmoothTalker TSR, which converts ASCII text into output instructions that generate good quality speech from the speaker. The Speech Thing package also includes capabilities for playing digitized (prerecorded) sounds as opposed to synthesized speech; STHING.DOC focuses on the speech synthesis capabilities. Although Covox supplies a version of the SmoothTalker TSR that will run on 4.77MHz 8088-based PC's, the quality of the speech on such a machine is not very good. Realistically, you need an 8Mhz 8088 or a 286 or 386 machine to get good speech quality. When running on a 16MHz 286 machine (my development system), the Speech Thing produces speech quality that rivals that of $1000 dedicated speech processing systems. The programming interface that Covox supplies for the Speech Thing is aimed toward Basic and C programmers. This document describes a Turbo Pascal unit, STHING, which makes it easy for Turbo Pascal (version 5.0 or later) programmers to add synthesized speech capabilities to their programs. It also describes two programs, STRES and TPTALK, which demonstrate some of the capabilities of the unit. We assume throughout that you have the Covox Speech Thing User Manual to refer to as needed. If you don't already have a Speech Thing, you can contact Covox as follows: Covox, Inc. 675 Conger St. Eugene, OR 97402 tel: 503-342-1271 fax: 503-342-1283 bbs: 503-342-4135 The Turbo Pascal code provided here is Copyright (C) 1990 TurboPower Software, all rights reserved. We hereby grant rights to other programmers to use this code in their own programs, for personal or commercial use, at no charge. You may freely distribute the files contained in this archive, including STHING.DOC, STHING.PAS, STHING.ASM, STHING.OBJ, STRES.PAS, STRES.EXE, and TPTALK.PAS. You may *not* sell any of the files (with the exception of nominal handling fees charged by bulletin board operators and shareware software distributors) without the express written consent of TurboPower Software. The SPEECHV2 and SPEECHV3 programs and other parts of the Speech Thing itself are the property of Covox, Inc. See the Speech Thing license agreement for information about using these programs. Overview of the STHING Unit --------------------------------------------------------------------------- STHING is a Turbo Pascal unit that provides procedures and functions for accessing all of the speech synthesis capabilities of the Speech Thing. In order for STHING to work, you must first load either the SPEECHV2 or SPEECHV3 memory resident program prior to calling the routines in STHING. It is not necessary for you to load Covox's STALK memory resident program, which is designed to make it easy for Basic programmers to access SPEECHVx. STALK is not necessary and in fact adds time and memory overhead for Turbo Pascal programs. STHING's initialization block searches for the signature of the SPEECHVx TSR. If the signature isn't found, STHING's StLoaded function will return False and none of the other routines will do anything. (It's still safe to call them, however.) If the signature is found, STHING initializes the Speech Thing as follows: - speech output is sent to the LPT1 port - speech tone, volume, pitch, and speed are set to default values - the SPEECHV3 hook routine that determines which keystrokes can interrupt speech is redirected to the STHING unit All of these defaults may be changed by calling other routines provided by STHING. For explanation of the third item, see the section "Interrupting Speech in Progress" below. The simplest program that should produce speech is the following: program Speak1; uses SThing; begin StSpeak('hello world'); end. If your Speech Thing interface plug is attached to a parallel port other than LPT1, you need to add one more statement: program Speak2; uses SThing; begin StSetLptPort(2); {Sets up for LPT2} StSpeak('hello world'); end. The supplied programs STRES and TPTALK demonstrate other features of the STHING unit. The routines in STHING can be organized in three groups: Basic Functions - set output port - set speech parameters - speak an ASCII string - modify ability to interrupt speech in progress - unload SPEECHVx from memory Phonetic Speech Functions - convert a text string to its phonetic representation - speak a string in phonetic representation Dictionary Functions - initialize or clear the dictionary - add or remove an entry in the dictionary - list the elements in the dictionary - write or read a dictionary file Detailed descriptions of each routine follow in the "STHING Reference Guide." Speech Dictionaries --------------------------------------------------------------------------- As Covox points out in its manual, the English language is notoriously tricky about pronunciation rules. The speech dictionary provides a means to improve the quality of synthesized speech for words that don't follow standard rules of pronunciation. Each entry in the dictionary contains a text string representing the normal spelling of the word, and a phonetic text string (using the SmoothTalker phonetic codes shown in Appendix A of the Covox manual) representing how you'd like the word to sound. SPEECHVx automatically substitutes the specified pronunciation whenever it encounters a dictionary word in the text stream passed to it. Here's a short program that demonstrates the use of a speech dictionary: program Dict; uses SThing; var txst : string; phst : string; begin if not StLoaded then halt; {Clear the dictionary. Redundant here} StInitDict(True); {Speak a hard-to-pronounce word} writeln('ASCII before adding to dictionary'); StSpeak('ascii'); readln; {Add the correct pronunciation to the dictionary} if not StInsertDict('ascii', 'AEskIY') then writeln('out of memory'); {Speak the word again} writeln('ASCII after adding to dictionary'); StSpeak('ascii'); readln; {Display what's in the dictionary} writeln('Contents of dictionary'); StInitDict(false); StDumpDict(txst, phst); while txst <> '' do begin writeln('"', txst, '", "', phst, '"'); StDumpDict(txst, phst); end; readln; {Remove the word from the dictionary} StRemoveDict('ascii'); {Speak the word again} writeln('ASCII after removing from dictionary'); StSpeak('ascii'); readln; end. When you add a dictionary entry, SPEECHVx allocates a block of memory to hold the entry. Normally SPEECHVx allocates this memory directly from the DOS free memory pool. Although that makes sense for C and Basic programs, it often doesn't work for Turbo Pascal because all available DOS memory is usually allocated for the Turbo Pascal heap. To deal with this issue, the STHING unit takes over the DOS interrupt ($21) and converts requests for DOS memory into equivalent requests to the Turbo Pascal heap manager. There is only one disadvantage to the approach: it isn't possible to deallocate the memory allocated for dictionary entries on the Turbo Pascal heap. If you have an application that needs to add and remove lots of dictionary entries, you should set STHING's boolean typed constant StAllocFromHeap to False as soon as your program starts. Note that in this case your program must use a $M directive to assure that there is free DOS memory space from which SPEECHVx can allocate dictionary entries. One other point to keep in mind: a dictionary remains active for only so long as the program which created it remains active. That is, as soon as your program halts, the dictionary is cleared. (A dictionary created by a TSR remains active as long as the TSR remains loaded.) For this reason, it's usually important to save dictionaries to a dictionary file before an application halts and to reload them when the program starts. Determining the best phonetic codes for a word is not a job for the impatient. However, in some cases it is well worth the effort. The StTextToPhonetic procedure will generate a first attempt at the codes by using SPEECHVx's own internal rules. Then you can modify the phonetic string by referring to Appendix A of the Speech Thing manual. Interrupting Speech in Progress --------------------------------------------------------------------------- When SPEECHV3 is loaded, you can interrupt speech in progress by pressing any key, with the exception of the Shift and Alt keys. SPEECHV2 does not offer this interrupt capability. SPEECHV3's behavior is a little annoying, at least for people who are accustomed to using WordStar editing keystrokes, because speech is interrupted when the Ctrl key is held down. SPEECHV3 provides a hook to modify its behavior in this regard. Whenever it checks whether speech should be interrupted, it issues an interrupt $7E. If the int $7E handler returns AX <> 0, speech output will be aborted and control will return to the calling application. The STHING unit takes over int $7E with a handler that provides the following behavior: any key that inserts a real keystroke into the keyboard buffer will interrupt speech. (This definition excludes the Ctrl, Alt, Shift, NumLock, and ScrollLock keys.) The keystroke causing the interruption remains in the keyboard buffer where it can be processed by the underlying application. You can restore SPEECHV3's default behavior by calling STHING's StRestoreInt7E procedure. If you need different behavior, you can install your own int $7E handler. Be sure to study the handler in STHING.ASM before writing your own. STHING Reference Guide --------------------------------------------------------------------------- The procedures and functions of STHING are described here in alphabetical order. ------------------------- procedure StDumpDict(var TextSt : string; var PhonSt : string); Call this routine repeatedly to retrieve all entries in the dictionary. The text strings are returned in alphabetical order, always in uppercase. When there are no more entries, TextSt returns an empty string. Call StInitDict first to reset the internal dictionary position pointer. Example: StInitDict(False); StDumpDict(TextSt, PhonSt); while TextSt <> '' do begin writeln(TextSt:40, PhonSt:40); StDumpDict(TextSt, PhonSt); end; ------------------------- procedure StGetParams(var Tone, Volume, Pitch, Speed : Word); Returns the last speech parameters set. See StSetParams for more information. ------------------------- procedure StGrabInt7E; Modifies the abort-speech-on-keypressed behavior as described in the section "Interrupting Speech in Progress" above. Since STHING calls this routine automatically during initialization, you don't need to call it yourself unless you are restoring and grabbing int $7E repeatedly, as in a TSR. See STRES.PAS for an example. StGrabInt7E affects the behavior of SPEECHV3 only. ------------------------- procedure StInitDict(Clear : Boolean); Reset the dictionary. If Clear = True, all entries are removed. If Clear = False, the dictionary's internal position pointer is reset to prepare for an alphabetical scan of the dictionary. See StDumpDict for an example. ------------------------- function StInsertDict(TextSt : string; PhonSt : string) : Boolean; Insert a new entry in the dictionary. Returns False if insufficient memory. If STHING's global typed constant StAllocFromHeap is True, StInsertDict allocates memory space from the Turbo Pascal heap; otherwise it allocates memory from the DOS free pool by using DOS function $48. ------------------------- function StLoaded : Boolean; Returns True if SPEECHVx is loaded, False otherwise. The other STHING routines don't do anything if StLoaded returns False. ------------------------- procedure StPhoneticSpeak(St : string); Speak the specified phonetic string. See Appendix A of the Speech Thing manual for information about acceptable phonetic codes. You should not surround strings passed to StPhoneticSpeak with << and >> strings, which are used only when mixing phonetic codes into normal text. ------------------------- function StReadDictFile(FName : string) : Word; Read dictionary from a text file, returning status. The status value is a standard Turbo Pascal IoResult code, with the following additions: 8 StInsertDict returned False 106 Invalid dictionary file 65535 SPEECHVx is not loaded See StWriteDictFile for more information about the file format. ------------------------- procedure StRemoveDict(TextSt : string); Remove an entry previously added to dictionary. If TextSt is not found in the dictionary, StRemoveDict does nothing. If the STHING typed constant StAllocFromHeap is True, heap space is NOT reclaimed by this call. ------------------------- procedure StRestoreInt7E; Restore abort-speech-on-keypressed behavior to the default for SPEECHV3. ------------------------- procedure StSetLptPort(LPTNumber : Byte); Set Speech Thing peripheral port for LPT 1, 2, or 3. STHING automatically initializes for LPT1. Also see StSetPort, which allows specification of an arbitrary port not associated with an LPT device. ------------------------- procedure StSetParams(Tone, Volume, Pitch, Speed : Word); Set parameters, as follows: valid range default ----------- ------- Tone 0..1 0 Volume 0..9 5 Pitch 0..9 5 Speed 0..9 5 StSetParams does not range-check the values it receives. ------------------------- procedure StSetPort(Port : Word); Set peripheral port where speaker output goes. Note that the value passed here is a hardware port number, not an LPT number. StSetPort interprets Port=0 as a special case meaning the port associated with LPT1. StSetPort should be called only when using a Voice Master or another Covox product to emulate a Speech Thing. ------------------------- procedure StSpeak(St : string); Speak the specified text string using the previously defined speech parameters for tone, volume, pitch, and speed. Note that you can pass a maximum of 255 characters at a time. If the text stream to speak exceeds 255 characters it is your responsibility to parse it into shorter chunks. StSpeak doesn't return until the string has been completely spoken, unless the speech is interrupted by a keystroke. ------------------------- procedure StTextToPhonetic(TextSt : string; var PhonSt : string); Returns the phonetic codes for the given text string, using SPEECHVx's internal conversion rules. Note that the length of the phonetic codes often exceeds that of the text string. It's your responsibility to limit TextSt's length so that PhonSt doesn't overflow. ------------------------- procedure StUnload; Unloads the resident copy of SPEECHV2 or SPEECHV3 from memory. After calling StUnload, StLoaded will always return False. Note that you can unload SPEECHV3 from the DOS command line by entering SPEECHV3 /Q. SPEECHV2 does not offer this command line capability, but it may still be unloaded by calling StUnload. ------------------------- function StWriteDictFile(FName : string) : Word; Write current dictionary to a file, returning status. The status value is a standard Turbo Pascal IoResult code, with the following addition: 65535 SPEECHVx is not loaded A dictionary file is a standard text file, with each line representing one dictionary entry or a comment. Blank lines and lines beginning with a semicolon are treated as comments. Other lines must contain a text word followed by one or more spaces followed by the phonetic representation (which may contain embedded spaces). The case (upper or lower) of the text word isn't important, but the case of the phonetic representation must exactly match the codes given by Covox. Here's an example of a valid dictionary file: ;these entries just encode the standard pronunciations ARBITRARILY AArbIXtrEHr4IXl3IY ARBITRATOR AArbIXtr4EYDX3ER COMPUTER kAXmpy4UWDX3ER DICTIONARY dIHkSHAXn4EHr3IY TPTALK - simple demonstration of STHING --------------------------------------------------------------------------- TPTALK is a simple program that demonstrates the STHING unit. If you specify the name of an ASCII text file on the command line when you call TPTALK, it will read the file for you. If don't specify a file name, you can enter text and TPTALK will speak each line as you enter it and write the phonetic representation of the line. In general, TPTALK does the same thing as the TALK program supplied with the Speech Thing. TPTALK accepts the following command line options: /? show a list of options /T n specify tone (0 or 1) /I n specify pitch (0..9) /S n specify speed (0..9) /V n specify volume (0..9) /L n specify LPT port (1..3) Unlike TALK, TPTALK won't load the SPEECHVx program if it isn't already loaded. Note that TPTALK needs only SPEECHV2 or SPEECHV3; it is *not* necessary to load STALK. TPTALK is provided only in source code format. You can compile it by running the Turbo Pascal compiler and doing a make in the same directory where STHING.PAS and STHING.OBJ reside. STRES - a memory resident screen reader --------------------------------------------------------------------------- STRES is a memory resident program for reading text screens and speaking them via the Covox Speech Thing. Before loading STRES you must first load SPEECHV2 or SPEECHV3. Note that it is *not* necessary to load Covox's STALK memory resident program. STRES is loaded with the following command line: STRES [options] [dictionaryfile] You may specify the following command line options: /? display a help screen but don't make STRES resident /L n specify line printer port (1..3) /S speak installation messages /U unload STRES from memory The optional dictionary file must be in the format described under the StWriteDictFile function above. The following hot keys activate STRES once it has been loaded: [Ctrl-RightShift-R] for screen reader mode [Ctrl-RightShift-S] to speak whole screen In screen reader mode the following keys are supported: [Up] read next line up [Down] read next line down [Left] read next character left [Right] read next character right [Ctrl-Left] read next word left [Ctrl-Right] read next word right [Home] move cursor to left edge of screen [End] move cursor to right edge of screen [PgUp] move cursor to top of screen [PgDn] move cursor to bottom of screen [Enter],[Esc] exit from reader mode Although the cursor is moved while STRES is reading from the screen, its position is restored when you press [Enter] or [Esc]. You can interrupt the full screen speech by pressing any key. If you activate STRES while in graphics mode, it will say "not in text mode." You can type STRES /? for a summary of options and commands. Or type STRES /S /? for a spoken summary. STRES.PAS requires TurboPower Software's Object Professional library (see below) to compile. STRES.EXE is provided in this same archive. About TurboPower Software --------------------------------------------------------------------------- TurboPower Software develops and markets add-on packages that make Turbo Pascal programmers more productive. Here's a brief description of current products: Object Professional An object-oriented library of over 100 object types and 2000 methods for writing sophisticated text mode user interfaces, for creating memory resident programs, and for solving many other common programming problems. Requires Turbo Pascal 5.5. List price $150. Turbo Professional The non-object-oriented predecessor to Object Professional. Has most of the same capabilities. Requires Turbo Pascal 4.0 or later. List price $125. B-Tree Filer A library of routines for writing single or multi-user database applications in Turbo Pascal. Also includes routines for direct access of network capabilities such as message passing and print spooler control. Supports all common PC networks. Requires Turbo Pascal 4.0 or later. List price $125 for the single user version, $175 with network support. Turbo Analyst A collection of utilities for documenting, analyzing, and improving Turbo Pascal programs. Includes cross-referencing, program indexing, program listing, pretty printing, execution profiling, and an integrated environment to make the whole process easy and pleasant. Supports Turbo Pascal 4.0 or later. List price $99. TurboPower also publishes the BIGED ("Big Ed") text editor, which displays text in graphics mode at larger than normal sizes for vision-impaired computer users. We will soon release a shareware version of BIGED that also provides speech output using the Covox Speech Thing. For further information, contact TurboPower at: TurboPower Software P.O. Box 66747 Scotts Valley, CA 95067 tel: 408-438-8608 fax: 408-438-8610 CompuServe: 76004,2611 ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of Public (software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. PsL cannot debug pro- programs over the telephone, though we can answer questions. Disks in the PsL are updated monthly, so if you did not get this disk directly from the PsL, you should be aware that the files in this set may no longer be the current versions. Also, if you got this disk from another vendor and are having prob- lems, be aware that some files may have become corrupted or lost by that vendor. Get a current, working disk from PsL. For a copy of the latest monthly software library newsletter and a list of the 2,000+ disks in the library, call or write Public (software) Library P.O.Box 35705 - F Houston, TX 77235-5705 1-800-2424-PSL MC/Visa/AmEx/Discover Outside of U.S. or in Texas or for general information, Call 1-713-524-6394 PsL also has an outstanding catalog for the Macintosh.